// Copyright 2016 The PDFium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com

#ifndef CORE_FPDFAPI_PARSER_CPDF_OBJECT_H_
#define CORE_FPDFAPI_PARSER_CPDF_OBJECT_H_

#include <stdint.h>

#include <set>
#include <type_traits>

#include "core/fxcrt/fx_string.h"
#include "core/fxcrt/retain_ptr.h"

class CPDF_Array;
class CPDF_Boolean;
class CPDF_Dictionary;
class CPDF_Encryptor;
class CPDF_IndirectObjectHolder;
class CPDF_Name;
class CPDF_Null;
class CPDF_Number;
class CPDF_Reference;
class CPDF_Stream;
class CPDF_String;
class IFX_ArchiveStream;

// ISO 32000-1:2008 defines PDF objects. When CPDF_Parser parses a PDF object,
// it represents the PDF object using CPDF_Objects. Take this PDF object for
// example:
//
// 4 0 obj <<
//   /Type /Pages
//   /Count 1
//   /Kids [9 0 R]
// >>
//
// Multiple CPDF_Objects instances are necessary to represent this PDF object:
// 1) A CPDF_Dictionary with object number 4 that contains 3 elements.
// 2) A CPDF_Name for /Pages.
// 3) A CPDF_Number for the count of 1.
// 4) A CPDF_Array for [9 0 R], which contains 1 element.
// 5) A CPDF_Reference that references object 9 0.
//
// CPDF_Object (1) has an object number of 4. All the other CPDF_Objects are
// inline objects. CPDF_Object represent that by using an object number of 0.
class CPDF_Object : public Retainable {
 public:
  static constexpr uint32_t kInvalidObjNum = static_cast<uint32_t>(-1);
  enum Type {
    kBoolean = 1,
    kNumber,
    kString,
    kName,
    kArray,
    kDictionary,
    kStream,
    kNullobj,
    kReference
  };

  uint32_t GetObjNum() const { return m_ObjNum; }
  void SetObjNum(uint32_t objnum) { m_ObjNum = objnum; }
  uint32_t GetGenNum() const { return m_GenNum; }
  void SetGenNum(uint32_t gennum) { m_GenNum = gennum; }
  bool IsInline() const { return m_ObjNum == 0; }
  uint64_t KeyForCache() const;

  virtual Type GetType() const = 0;

  // Create a deep copy of the object.
  virtual RetainPtr<CPDF_Object> Clone() const = 0;

  // Create a deep copy of the object except any reference object be
  // copied to the object it points to directly.
  RetainPtr<CPDF_Object> CloneDirectObject() const;

  virtual ByteString GetString() const;
  virtual WideString GetUnicodeText() const;
  virtual float GetNumber() const;
  virtual int GetInteger() const;

  // Can only be called for objects of types: `kBoolean`, `kNumber`, `kName`,
  // and `kString`.
  virtual void SetString(const ByteString& str);

  virtual CPDF_Array* AsMutableArray();
  virtual CPDF_Boolean* AsMutableBoolean();
  virtual CPDF_Dictionary* AsMutableDictionary();
  virtual CPDF_Name* AsMutableName();
  virtual CPDF_Null* AsMutableNull();
  virtual CPDF_Number* AsMutableNumber();
  virtual CPDF_Reference* AsMutableReference();
  virtual CPDF_Stream* AsMutableStream();
  virtual CPDF_String* AsMutableString();

  virtual bool WriteTo(IFX_ArchiveStream* archive,
                       const CPDF_Encryptor* encryptor) const = 0;

  // Create a deep copy of the object with the option to either
  // copy a reference object or directly copy the object it refers to
  // when |bDirect| is true.
  // Also check cyclic reference against |pVisited|, no copy if it is found.
  // Complex objects should implement their own CloneNonCyclic()
  // function to properly check for possible loop.
  virtual RetainPtr<CPDF_Object> CloneNonCyclic(
      bool bDirect,
      std::set<const CPDF_Object*>* pVisited) const;

  // Return a reference to itself.
  // The object must be direct (!IsInlined).
  virtual RetainPtr<CPDF_Reference> MakeReference(
      CPDF_IndirectObjectHolder* holder) const;

  RetainPtr<const CPDF_Object> GetDirect() const;    // Wraps virtual method.
  RetainPtr<CPDF_Object> GetMutableDirect();         // Wraps virtual method.
  RetainPtr<const CPDF_Dictionary> GetDict() const;  // Wraps virtual method.
  RetainPtr<CPDF_Dictionary> GetMutableDict();       // Wraps virtual method.

  // Const methods wrapping non-const virtual As*() methods.
  const CPDF_Array* AsArray() const;
  const CPDF_Boolean* AsBoolean() const;
  const CPDF_Dictionary* AsDictionary() const;
  const CPDF_Name* AsName() const;
  const CPDF_Null* AsNull() const;
  const CPDF_Number* AsNumber() const;
  const CPDF_Reference* AsReference() const;
  const CPDF_Stream* AsStream() const;
  const CPDF_String* AsString() const;

  // Type-testing methods merely wrap As*() methods.
  bool IsArray() const { return !!AsArray(); }
  bool IsBoolean() const { return !!AsBoolean(); }
  bool IsDictionary() const { return !!AsDictionary(); }
  bool IsName() const { return !!AsName(); }
  bool IsNull() const { return !!AsNull(); }
  bool IsNumber() const { return !!AsNumber(); }
  bool IsReference() const { return !!AsReference(); }
  bool IsStream() const { return !!AsStream(); }
  bool IsString() const { return !!AsString(); }

 protected:
  friend class CPDF_Dictionary;
  friend class CPDF_Reference;

  CPDF_Object() = default;
  CPDF_Object(const CPDF_Object& src) = delete;
  ~CPDF_Object() override;

  virtual const CPDF_Object* GetDirectInternal() const;
  virtual const CPDF_Dictionary* GetDictInternal() const;
  RetainPtr<CPDF_Object> CloneObjectNonCyclic(bool bDirect) const;

  uint32_t m_ObjNum = 0;
  uint32_t m_GenNum = 0;
};

template <typename T>
struct CanInternStrings {
  static constexpr bool value = std::is_same<T, CPDF_Array>::value ||
                                std::is_same<T, CPDF_Dictionary>::value ||
                                std::is_same<T, CPDF_Name>::value ||
                                std::is_same<T, CPDF_String>::value;
};

#endif  // CORE_FPDFAPI_PARSER_CPDF_OBJECT_H_
`CPDF_Object` 是一个抽象基类，用于表示 PDF 文档中的不同类型的对象。以下是 `CPDF_Object` 提供的接口功能：

### 类 `CPDF_Object`

#### 常量定义
1. * *kInvalidObjNum * *：定义无效对象编号，为 `-1` 的静态常量。

#### 枚举类型
2. * *enum Type** ：枚举类型，用于标识 PDF 对象的具体类型：
- `kBoolean`
- `kNumber`
- `kString`
- `kName`
- `kArray`
- `kDictionary`
- `kStream`
- `kNullobj`
- `kReference`

#### 基本属性和方法
3. * *uint32_t GetObjNum() const** ：
- 获取对象编号。

4. * *void SetObjNum(uint32_t objnum) * *：
- 设置对象编号。

5. * *uint32_t GetGenNum() const** ：
- 获取生成编号。

6. * *void SetGenNum(uint32_t gennum) * *：
- 设置生成编号。

7. * *bool IsInline() const** ：
- 判断对象是否为内联对象。

8. * *uint64_t KeyForCache() const** ：
- 获取缓存的关键字。

#### 纯虚函数（子类需要实现）
9. * *virtual Type GetType() const = 0 * *：
- 获取对象类型。

10. * *virtual RetainPtr<CPDF_Object> Clone() const = 0 * *：
- 深拷贝对象。

11. * *virtual bool WriteTo(IFX_ArchiveStream * archive, const CPDF_Encryptor * encryptor) const = 0 * *：
- 将对象写入到档案流。

#### 常见虚函数
12. * *RetainPtr<CPDF_Object> CloneDirectObject() const** ：
- 深拷贝对象，包括任何引用对象。

13. * *virtual ByteString GetString() const** ：
- 获取字符串。

14. * *virtual WideString GetUnicodeText() const** ：
- 获取 Unicode 文本。

15. * *virtual float GetNumber() const** ：
- 获取数字值。

16. * *virtual int GetInteger() const** ：
- 获取整数值。

17. * *virtual void SetString(const ByteString & str) * *：
- 设置字符串值。

#### 类型转换方法
18. * *virtual CPDF_Array * AsMutableArray() * *
19. * *virtual CPDF_Boolean * AsMutableBoolean() * *
20. * *virtual CPDF_Dictionary * AsMutableDictionary() * *
21. * *virtual CPDF_Name * AsMutableName() * *
22. * *virtual CPDF_Null * AsMutableNull() * *
23. * *virtual CPDF_Number * AsMutableNumber() * *
24. * *virtual CPDF_Reference * AsMutableReference() * *
25. * *virtual CPDF_Stream * AsMutableStream() * *
26. * *virtual CPDF_String * AsMutableString() * *

#### 其他功能
27. * *RetainPtr<CPDF_Object> CloneNonCyclic(bool bDirect, std::set<const CPDF_Object*>*pVisited) const** ：
- 深拷贝对象，避免循环引用问题。

28. * *RetainPtr<CPDF_Reference> MakeReference(CPDF_IndirectObjectHolder * holder) const** ：
- 返回对象的引用。

29. * *RetainPtr<const CPDF_Object> GetDirect() const**
30. * *RetainPtr<CPDF_Object> GetMutableDirect() * *

31. * *RetainPtr<const CPDF_Dictionary> GetDict() const**
32. * *RetainPtr<CPDF_Dictionary> GetMutableDict() * *

#### 类型检测方法（通过转换方法实现）
33. * *const CPDF_Array * AsArray() const**
34. * *const CPDF_Boolean * AsBoolean() const**
35. * *const CPDF_Dictionary * AsDictionary() const**
36. * *const CPDF_Name * AsName() const**
37. * *const CPDF_Null * AsNull() const**
38. * *const CPDF_Number * AsNumber() const**
39. * *const CPDF_Reference * AsReference() const**
40. * *const CPDF_Stream * AsStream() const**
41. * *const CPDF_String * AsString() const**

#### 类型判定方法
42. * *bool IsArray() const**
43. * *bool IsBoolean() const**
44. * *bool IsDictionary() const**
45. * *bool IsName() const**
46. * *bool IsNull() const**
47. * *bool IsNumber() const**
48. * *bool IsReference() const**
49. * *bool IsStream() const**
50. * *bool IsString() const**

#### 模板结构
51. * *template <typename T> struct CanInternStrings** ：
- 用于判断是否可以进行字符串内联。

这些接口和方法提供对 PDF 对象的类型检测、转换、深拷贝以及导出功能，加强了对 PDF 对象的管理和操作能力。